Zero to Quarto Workshop

Making your first quarto website

About me

Chi Zhang

Statistician and R developer

Quarto has become one of my main activities post-phd

  • teach biostatistics with quarto websites;
  • build personal portfolio;
  • collaborate with non-coding colleagues;
  • personal note-taking system …

About this workshop

Quarto is the new way of open source publishing, and it can do so many things:

Reports and books; presentation; websites; … Each is a project.


Today we build a quarto website, and use GitHub Pages to publish it.

  • What makes a quarto project?
  • Build and publish on GitHub
  • Adding content: navigation, code and more
  • time permits: interactivity with webr; …

About this workshop

Workshop website with step-by-step tutorial:

https://andreaczhang.github.io/workshop-02quarto/


Workshop website template for you to download and modify:

https://andreaczhang.github.io/template-02quarto/


Please clone the template repository to your local machine :)

Practice 1: Set up a version controlled quarto project

Note

You need

  • Github account
  • Rstudio (latest version; at least late 2022)
  • Quarto (v1.2 or 1.3)


(Follow the step-by-step tutorial part 1)

A minimal Quarto Project

What’s in a Quarto project?

  • _quarto.yml: meta-data (e.g. layout)
  • index.qmd: homepage
  • styles.scss: theme (color and fonts)

_quarto.yml

In this file, some basic information of the project is specified, such as project type, layout, theme.

This is where you modify how the website looks like.

project:
  type: website
  output-dir: docs

website:
  page-navigation: true
  title: "Zero to Quarto Workshop"

  navbar:
    left:
      - href: index.qmd
        text: Home

    right: 
      - icon: github
        href: https://github.com
        
format:
  html:
    # theme: zephyr
    theme: styles.scss
    toc: true

index.qmd

Your homepage: when others click the URL you shared with them, this is where they land.

Content blocked by --- is the YAML header, which appears at the top of your page. Author, date can be specified here.

---
title: "Zero to Quarto Workshop"
subtitle: "Build your first quarto website (or some other cool things!)"
format: 
  html:
    toc: true
    toc-depth: 2
---

Date: **Monday 23 October 2023, 6:30PM to 8:00PM, CEST** 
------------------
 
# Welcome!

Quarto is one of the most discussed topics in the R community for the past year. In the posit conf 2023 that just happened a few weeks ago, there were 23 (!) talks on this open-source publishing system. You can build a personal or organisation website; a course or workshop website; a blog; a scientific report; a presentation; all with the possibility to display and execute code (R, Python, Julia), and for free.

styles.scss

This file is optional; but good to have - when you want to customize the color and fonts.

However, if you are happy with the quarto preset themes, styles.scss is not necessary for the website to work.

/*-- scss:defaults --*/
$theme-black: #4c4c4c;
$theme-white: white;
$theme-grey: #FAFAFA;
$theme-beige: #FFFEF2;
$theme-purple0: #FFF0F5;
$theme-purple1: #E6E6FA;
$theme-purple2: #CBC3E3;
$theme-purple3: #88398A;
$theme-purple4: #9d709e;
$theme-purple5: #562457;


$body-bg: $theme-white;
$body-color: $theme-black; // text color
$headings-color: $theme-purple5; // applies to all 
$link-color: $theme-purple4;

Practice 2: Render your quarto project

Open index.qmd, find the render button. Click.

Do you see a HTML page in your Viewer?

Publish with GitHub Pages

Practice 3: configure your quarto project

You need two more things before pushing everything to GitHub.


Set output-dir to docs in _quarto.yml

project:
  type: website
  output-dir: docs


Create .nojekyll file

In terminal (or your favorite command line editor),

touch .nojekyll


Render one last time, now commit everything, push to remote (GitHub).

Practice 4: Configure GH Pages

Go to Setting > Pages > Build and deployment, choose Deploy from a branch.

Under Branch, select /docs. Save. It should take less than 1 minute to complete.

Your site should be available at https://your_username.github.io/repo_name.

Add content to your website

Theme

Theme is controlled in _quarto.yml as well.

  • for quarto preset themes, specify the names (such as cosmo, zephyr);
  • for customized themes (such as the one used in he workshop), provide a styles.scss file where you have different colors and fonts.
format:
  html:
    # theme: zephyr
    theme: styles.scss
    toc: true

Practice 5: Add a new page to your website

It is always a good idea to add an about page to your website!


Tasks

Try to create an about.qmd file, write a few lines about what kind of website you wnat to create.


Position it to the right of the home page.


Test out a few quarto themes, and/or use different colors specified in styles.scss (optional).

Add content to your website (part 2)

Figures and tables

One (of a few) way to add a figure:

![](path_to_figure.png) 
![caption](path_to_figure.png) {width=85% fig-align="center"}


One (of a few) way to add a table:

| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12      | 12   |    12 |   12   |
| 123     | 123  |   123 |  123   |

: Table name

Read about how to work on figures and tables.

Code chunks

Use a code fence (3 backticks) with the language you wish to run the code.

Summary

Today we went through 4 steps:

  • set a version controlled quarto project
  • build the project locally, configure necessary parts (output-dir and .nojekyll)
  • push to GitHub, configure GH pages setting
  • add more content

Learn more

  • Quarto Gallery shows a nice and inspiring collection of the types of projects you can create. Make sure you check them out!
  • Official guide on creating website, book, presentation and more.

Practice 6: Add a plot to your website

Experiment with adding content to your website:

  • reproduce the code chunk example in a quarto document; (you need ggplot2 package to do it)
  • find a figure, try to include it in your quarto document